Node / ReticulumProjects / MeshChatX.git / files / docs / agents / overview.md

Displaying Rendered • View raw • Download

Project brief for automated agents and contributors.

Conventions and task skills live under T383838docs/agents/. This file is the durable source of truth for architecture and invariants.

Reticulum MeshChatX is a local-first mesh communications client on the Reticulum Network Stack.

It is an independent fork of Reticulum MeshChat and is not affiliated with the upstream project.

Core protocols:

• Reticulum (RNS) - identities, paths, interfaces, encrypted transport

• LXMF - messaging, attachments, propagation nodes

• LXST - audio calls and telephony

One Python process owns the web server, Reticulum stack, and per-identity managers.

The Vue frontend is static assets served from T383838meshchatx/public/ after a Vite build.

Electron and Android wrap the same backend.

Website: meshchatx.com

Source: github.com/Quad4-Software/MeshChatX

• Local-first. Works on desktop, mobile, containers, and SBCs.

• Preserve Reticulum / LXMF / LXST semantics while improving UX and ops tooling.

• Multiple identities in one process without cross-identity data leakage.

• Python backend and Vue frontend independently testable.

• Predictable SQLite behaviour in constrained environments.

• Prefer identity-scoped state, explicit migrations, and narrowly declared plugin permissions.

MeshChatX sits on Reticulum. Agents must not invent cloud-era or IP-era designs for mesh features.

• Philosophy: Zen of Reticulum

• Conventions: T383838docs/agents/conventions/reticulum-zen.md

• Checklist skill: T383838docs/agents/skills/reticulum-design-gates/SKILL.md

• Always-on editor rule (when present): reticulum Zen gates under project rules

Short form: no mandatory cloud center, address destination hashes, assume hostile links, design for scarcity and delay, keep code transport-agnostic, keep identity state scoped.

T282828

Critical lifecycle facts:

• HTTP can bind before RNS/identity finish starting. T383838/api/v1/status reports T383838starting / T383838ok / T383838failed with T383838stage and T383838network_ready.

• CLI one-shots (T383838--self-check, backup/restore helpers) still initialize synchronously.

• Switching identities tears down the old T383838IdentityContext and loads another. Do not stash identity-specific state in process globals.

Business rules belong in backend managers under T383838meshchatx/src/backend/.

Keep T383838meshchat.py focused on transport and lifecycle when possible.

• Python T383838>=3.11 (CI commonly runs 3.14)

• Node.js T383838>=24, pnpm from T383838package.json T383838packageManager

• UV for Python deps

• Task for common workflows

Prefer Task targets over inventing one-off scripts:

T282828

Optional RNS/rngit tooling (requires mesh reachability, can sometimes be significantly slower than PyPI):

T282828

Useful focused commands:

T282828

uv run pytest tests/backend/test_<name>.py -q --tbTff7b72=short

pnpm Tffa657exec vitest run tests/frontend/<Name>.test.js

pnpm Tffa657exec eslint <file> --fix

uv run python -m meshchatx.meshchat --self-check

Default storage root: T383838./storage (override with T383838--storage-dir / T383838MESHCHAT_STORAGE_DIR).

Android may prefer external app files storage.

Per identity:

T282828

Shared outside identity storage:

• Reticulum config: T383838~/.reticulum by default (T383838--reticulum-config-dir / T383838MESHCHAT_RETICULUM_CONFIG_DIR)

• Interfaces and transport settings live with Reticulum, not only in the identity DB

These are different operations. Do not conflate them in UI copy or code paths.

Identity export download should use a real extension such as T383838identity.bin.

File pickers for keys should accept T383838.bin, T383838.key, T383838.identity, T383838application/octet-stream, and T383838*/*.

Database restore pickers stay T383838.zip.

• Engine: SQLite with explicit SQL and versioned migrations (no ORM).

• Schema changes go through migrations in the database schema layer.

• Backups and snapshots are first-class recovery tools. Prefer restore APIs over hand-editing DB files.

• Conversation list / sidebar queries must stay slim. Truncate content previews. Derive attachment flags in SQL. Do not ship multi-MB T383838fields blobs in list endpoints.

• Worker-thread DB connections must apply the same pragmas as the main connection via T383838DatabaseProvider (especially T383838temp_store).

On Linux, MeshChatX can apply a Landlock filesystem sandbox after startup.

Control with T383838MESHCHAT_LANDLOCK (T3838381 force on, T3838380 force off, unset = auto when kernel supports it).

Critical SQLite interaction:

• Under Landlock, T383838PRAGMA temp_store=FILE can break complex conversation queries with T383838unable to open database file.

• Default worker connections to T383838temp_store=MEMORY.

• Memory-pressure mode may shrink cache/mmap. While Landlock is active, keep MEMORY temp.

• Without Landlock, FILE temp plus a storage-local T383838sqlite-tmp TMPDIR is acceptable.

Landlock apply is process-wide and one-shot. Tests that enable it must run in a subprocess.

Also see T383838docs/en/platform-guides/linux-sandbox.md for Firejail / Bubblewrap host examples.

Defaults aim at secure local operation:

• HTTPS and WSS on by default (self-signed certs per identity when custom PEMs absent)

• Optional HTTP auth (T383838--auth / T383838MESHCHAT_AUTH=true)

• CSRF on mutating HTTP requests

• Encrypted session cookies

• CORS / CSP / defensive HTTP middleware

• Access-attempt logging and lockout when auth is enabled

• IP allowlisting available via app security settings

• Privacy mode can block outbound clearnet HTTP from app features (does not stop Reticulum mesh traffic)

Do not recommend exposing MeshChatX directly on the public internet without extra hardening.

Prefer bind T383838127.0.0.1, HTTPS, and auth if other local users share the host.

Sensitive config changes (for example auth enable / password hash) must use CSRF-protected HTTP endpoints, not unrestricted WebSocket mutators.

Local filesystem browse/upload/download/delete APIs must path-jail to a feature or identity root. See T383838docs/agents/conventions/path-jail.md and T383838docs/agents/skills/path-jail-local-fs/SKILL.md.

Password reset: T383838--reset-password or T383838MESHCHAT_RESET_PASSWORD=true clears the stored hash so a new password can be set in the UI.

Plugins are powerful and partially sandboxed. Treat install/enable paths as security-sensitive.

• Frontend plugins run in Workers with capability grants

• Backend WASM plugins use wasmtime with fuel / capability gates

• Backend Python plugins and Sideband loaders are higher risk and permission-gated / danger-switched

• Invalid RSG signatures hard-block install

• Tampered installed trees should disable as integrity failures

• Disable all plugins with T383838--disable-plugins / T383838MESHCHAT_DISABLE_PLUGINS=true

• REST under T383838/api/v1/*

• Frontend uses T383838window.api / T383838apiClient.js with CSRF on mutating calls

• WebSocket T383838/ws for live events (messages, identity switch, telephone, RRC, Nomad downloads, plugins, RNS link events)

• Typed WS handlers live in frontend registries (T383838wsEventRegistry / T383838wsEventBridge)

• Generic RNS Link API over WS (T383838rns.link.open|identify|request|send|close and T383838rns.link.event) for external tools and plugins. See T383838docs/en/rns-link-api.md.

When identity/network is not ready, prefer 503 with a retryable message over opaque 500 for temporary DB/startup failures.

• Vue 3 Options API is the dominant style. Match the file you edit.

• Routes are hash-based (for example T383838#/messages).

• New top-level pages need: route in T383838main.js, nav/tools entry when discoverable, i18n keys, tests.

• User-visible strings go through locale files (T383838meshchatx/src/frontend/locales/en.json at minimum).

• User-visible action outcomes use T383838ToastUtils.

• Do not use T383838_-prefixed keys in Vue T383838data() (T383838vue/no-reserved-keys).

• Contribution registries drive nav, tools, commands, settings sections, and WS events. Prefer extending registries over hardcoding one-off shell wiring.

• UI is a WebView. Backend runs via Chaquopy.

• File chooser: bare extension tokens like T383838.identity are not valid MIME types for T383838Intent.EXTRA_MIME_TYPES. Map them to T383838application/octet-stream / T383838*/*.

• Set multi-select only when the WebView chooser mode requests it.

• Storage setup (internal vs external) can create a fresh-looking install if the user picks a different location than previous data.

• External http(s) links should open in the system browser, not navigate the WebView away from the app.

Common overrides (CLI flags usually mirror these):

Restore helpers:

T282828

• Backend change → update T383838tests/backend/

• Frontend change → update T383838tests/frontend/

• API contract / route list fixtures may need updates when routes change

• Prefer focused suites in agent loops. Full T383838task test is heavy.

• Avoid piping long pytest runs through T383838| tail in automation shells (can hang the harness).

• Landlock-enable tests must use a subprocess.

• Long-running soak / some notification suites can hang. Use timeouts and isolate them unless explicitly requested.

• Self-check and CI matrices cover cross-platform boot, storage lock fallbacks, and critical HTTP/WS probes. Do not weaken those without cause.

• Prefer existing per-file SPDX headers. Project-owned files are typically T3838380BSD.

• Upstream-derived files may be MIT or dual-marked. Preserve obligations.

• Patch-oriented contribution flow is documented in T383838CONTRIBUTING.md (LXMF patch submission is first-class for some contributors).

• Generative AI policy in T383838CONTRIBUTING.md requires disclosure and human review. Do not submit unreviewed bulk-generated churn.

1. No emojis in code, markdown, or docs you write for this repo.

2. No TODO / FIXME noise comments.

3. No emdashes or semicolons in comments or docs you write.

4. No backticks in code comments. Prefer plain words or quoted identifiers.

5. Do not create markdown docs unless asked (except agent guidance under T383838docs/agents/ when requested).

6. Do not commit or push unless the user asks.

7. Do not generate exploit PoCs, malware, or attack tooling.

8. Prefer minimal diffs. Match nearby style.

9. Do not invent install/run flows when Taskfile already covers them.

10. Mesh-facing designs must pass Zen / architecture gates (T383838reticulum-zen.md / T383838reticulum-design-gates).

Before finishing work in these areas, verify the matching invariants:

1. Identity import / tutorial - key-only vs zip restore copy is correct, picker accepts real exports, activate-on-finish / skip paths do not orphan imports.

2. Conversations / notifications DB - slim queries, MEMORY temp under Landlock, 503 on retryable SQLite errors. Sidebar unread pills (messages, relay mentions, missed calls) stay in sync with read/viewed state. No header notification bell.

3. Auth / CSRF / WS config - no new unauthenticated mutating surfaces, no sensitive settings over open WS mutators.

4. Plugins - permissions declared, install preview/consent preserved, signatures/integrity not bypassed.

5. Android bridges - MIME mapping, storage paths, and WebView navigation guards remain correct.

6. Identity switch - no cross-identity leakage via caches, routers, or global singletons.

7. Migrations - schema version bump and upgrade path tested.

• T383838docs/agents/conventions/reticulum-zen.md - Zen of Reticulum hard gates

• T383838docs/agents/skills/reticulum-design-gates/SKILL.md - mesh design checklist

• T383838docs/en/architecture.md - design and process overview

• T383838docs/en/identity-and-security.md - identities, auth, privacy, backups

• T383838docs/en/getting-started.md - UI map and first-run workflow

• T383838docs/en/rns-link-api.md - generic RNS Link WebSocket API

• T383838docs/en/platform-guides/linux-sandbox.md - Firejail / Bubblewrap

• T383838docs/en/messaging.md - LXMF behaviour

• T383838CHANGELOG.md - version-facing behaviour changes

• T383838CONTRIBUTING.md - patch and AI disclosure policy

• T383838docs/agents/README.md - index of conventions and skills

• T383838docs/agents/conventions/ - surface-specific rules including Reticulum Zen and test oracles

• T383838docs/agents/skills/ - focused workflows including reticulum-design-gates, RRC / LXMF / LXST, pages, registries, identity restore/switch, Landlock/SQLite, migrations/backups, auth/CSRF/WS, plugins, RNS Link API, deferred startup, Electron packaging, Android bridge, test loop, test-oracles, and exploratory-testing